getProp

Type

control structure

Summary

Handles the message sent to an object when you access one of its custom properties.

Syntax

getProp <propertyName>
   <statementList>
end <propertyName>

Description

Use the getProp control structure to perform a transformation on a custom property before its value is returned to the handler that requested it, or to implement a virtual property (one that is implemented only in a handler).

Form: The first line of a getProp handler consists of the word "getProp" followed by the property's name.

The last line of a getProp handler consists of the word "end" followed by the property's name.

The property's value is returned to the calling handler by a return control structure within the getProp handler. (A getProp handler works much like a custom function handler, in the sense that it exists to return a value.)

The getProp call passes through the message path, so a getProp handler for an object can be located in the object's script or in the script of any object further in the message path. For example, a getProp handler for a card property may be located in the script of the stack that the card belongs to.

If you use a custom property of an object within a getProp control structure for the custom property in the object's own script, no getProp call is sent to the object. (This is to avoid runaway recursion, where the getProp handler calls itself.) This is only the case for the custom property that the current getProp handler applies to. Setting a different custom property does send a getProp call. So does setting the same custom property for an object other than the one whose script contains the getProp handler.

warning

If a getProp handler in one object's script uses the value of the custom property for a different object, and the first object is in the second object's message path, a runaway recursion will result. For example, if the following handler is in a stack script, and you get the "myCustomProperty" of a card in that stack, runaway recursion will result:

    getProp myCustomProperty
        put the myCustomProperty of the target into myVariable
        -- Because the target is the card, and this handler is in
        -- the stack, the above statement sends another getProp call
        -- to the card.
    end myCustomProperty

To avoid this problem, set the lockMessages property to true before checking the custom property.

You can include as many getProp handlers in a script as you need. The property that a getProp handler controls is determined by the propertyName parameter in the first line of the handler. (If a script contains two getProp handlers for the same property, the first one is used.)

note

You cannot use a getProp handler to intercept a call for the value of a built-in property. The getProp control structure can be used only for custom properties.

A getProp handler can be used to implement virtual properties for an object. A virtual property does not exist in the list of the object's custom properties. Instead, when a statement calls for the property's value, the getProp handler computes that value.

For example, the following getProp handler implements a virtual property of a field that contains a list of numbers:

    getProp columnAverage
        repeat for each line thisNumber of me
            add thisNumber to fieldTotal
        end repeat
        return fieldTotal/the number of lines of me
    end columnAverage

The "columnAverage" property of the field does not exist in the list of the field's custom properties. Instead, it is evaluated when a statement requests it:

    put the columnAverage of field \"Numbers\" into field \"Average\"

Parameters

Name	Type	Description
propertyName		The name of a custom property.
statementList		The statementList consists of one or more LiveCode statements, and can also include if, switch, try, or repeat control structures.

Related

object: stack

property: customPropertySets

command: get, call

constant: return

control structure: getProp, exit

function: paramCount, value

glossary: object, script, return, call, property, recursion, custom function, control structure, custom property, handle, message path, message, parameter, statement, handler

keyword: end, word, field, card

Compatibility and Support

Introduced

LiveCode 1.0

OS

mac

windows

linux

ios

android

Platforms

desktop

server

mobile